NeXTSTEP 3.3 (Developer)…68k, x86, SPARC, PA-RISC]/NeXTSTEP 3.3 Dev Intel.iso/NextDeveloper/Source/GNU/emacs/info/texinfo-2

Text File | 1991-01-10 | 50KB | 1,406 lines

Info file ../info/texinfo, produced by Makeinfo, -*- Text -*- from
input file texinfo.texinfo.

This file documents Texinfo, a documentation system that uses a
single source file to produce both on-line help and a printed manual.

This is edition 1.1 of the Texinfo documentation, and is for the
Texinfo that is distributed as part of Version 18 of GNU Emacs.

Copyright (C) 1988 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.



File: texinfo,  Node: Indices,  Prev: Contents,  Up: Ending a File

Creating Indices
================

Using Texinfo, you can generate printed indices and Info file menus
without having to sort and collate entries manually.  Texinfo will do
this for you automatically.  Each index covers a certain kind of
entry (functions, or variables, or concepts, etc.) and lists all of
those entries in alphabetical order, together with information on how
to find the discussion of each entry.  In a printed manual, this
information consists of page numbers.  In an Info file, it consists
of a menu item leading to the first node referenced.

When you are making index entries, it is good practice to think of
the different categories under which people may look for something.
Different people *do not* think of the same words when they look
something up.  They think of different words.  A helpful index will
have items indexed under all the different words that people may use.
For example, someone might think it obvious that the two letter names
for indices should be listed under "Indices, two letter names", since
the word "Index" is the general concept.  But another reader may
remember the specific concept of two letter names and search for the
entry listed as "Two letter names for indices".  A good index will
have both entries and will help both kinds of user.

Like typesetting, the construction of an index is a highly skilled,
professional art, the subtleties of which are not appreciated until
you have to do it yourself.

Normally, six indices are provided for:

   * A "program index" listing names of programs and leading to the
     places where those programs are documented.

   * A "function index" listing functions (such as, entry points of
     libraries).

   * A "variables index" listing variables (such as, external
     variables of libraries).

   * A "data type index" listing data types (such as, structures
     defined in header files).

   * A "keystroke index" listing keyboard commands.

   * A "concept index" listing concepts that are discussed.

Not every manual needs all of these.  This manual has two indices: a
concept index and an @-command index (that uses the function index
but is called a command index in the chapter heading).  Two or more
indices can be combined into one using the `@synindex' command.
*Note Combining Indices::.

* Menu:

* Index Entries::    Defining the entries of an index
* Combining Indices::
* Printing Indices & Menus::



File: texinfo,  Node: Index Entries,  Next: Combining Indices,  Up: Indices

Defining the Entries of an Index
--------------------------------

The data to make an index comes from many individual commands
scattered throughout the Texinfo source file.  Each command says to
add one entry to a particular index; after processing, it will give
the current page number or node name as the reference.

`@cindex CONCEPT'
     Make an entry in the concept index for CONCEPT, referring to the
     current page or node.

`@findex FUNCTION'
     Make an entry in the function index for FUNCTION, referring to
     the current page or node.

`@vindex VARIABLE'
     Make an entry in the variable index for VARIABLE, referring to
     the current page or node.

`@pindex PROGRAM'
     Make an entry in the program index for PROGRAM, referring to the
     current page or node.

`@kindex KEY'
     Make an entry in the key index for KEY, referring to the current
     page or node.

`@tindex DATA TYPE'
     Make an entry in the data type index for DATA TYPE, referring to
     the current page or node.

If the same name is indexed on several pages, all the pages are
listed in the printed manual's index.  However, *only* the *first*
node referenced will appear in the index of an Info file.  This means
that it is best to write indices in which each entry will refer to
only one place in the Texinfo file.  Fortunately, this constraint is
a feature rather than loss since it means that the index will be easy
to use.  Otherwise, it can be easy to create an index which has many
pages listed for an entry and you don't know which one you need.

You are not actually required to use indices for their canonical
purposes.  For example, you might wish to index some C preprocessor
macros.  You could put them in the function index along with actual
functions, just by writing `@findex' commands for them; then, when
you print the "function index", you could give it the title `Function
and Macro Index' and all will be consistent for the reader.  Or you
could put the macros in with the data types by writing `@tindex'
commands for them, and give that index a suitable title so the reader
will understand.



File: texinfo,  Node: Combining Indices,  Next: Printing Indices & Menus,  Prev: Index Entries,  Up: Indices

Combining Indices
-----------------

Sometimes you will want to combine two disparate indices such as
functions and variables, perhaps because you have few enough of one
of them that a separate index for them would look silly.

You could put variables into the function index by writing `@findex'
commands for them instead of `@vindex' commands, and produce a
consistent manual by printing the function index with the title
`Function and Variable Index' and not printing the `Variable Index'
at all; but this is not a robust procedure.  It works only as long as
your document is never included in part of or together with another
document that is designed to have a separate variable index; if you
did that, the variables from your document and those from the other
would not end up together.

What you should do instead when you want functions and variables in
one index is to index the variables with `@vindex' as they should be,
but use the `@synindex' command to redirect these `@vindex' commands
to the function index.  `@synindex' takes two arguments: the name of
an index to redirect, and the name of an index to redirect it to.
For this purpose, the indices are given two-letter names:

`cp'
     the concept index

`vr'
     the variable index

`fn'
     the function index

`ky'
     the key index

`pg'
     the program index

`tp'
     the data type index

Thus, `@synindex vr fn' at the front of a Texinfo file will cause all
entries designated for the variable index to go to the function index
instead.



File: texinfo,  Node: Printing Indices & Menus,  Prev: Combining Indices,  Up: Indices

Printing an Index and Generating Menus
--------------------------------------

To print an index means to include it as part of a manual or Info file.
This does not happen automatically just because you use `@cindex' or
other index-entry generating commands in the Texinfo file; those just
cause the raw data for the index to be accumulated.  To print an
index, you must include the `@printindex' command at the place in the
document where you want the index to appear.  Also, for the case of
the printed manual, you must run a program called `texindex' to sort
the raw data to produce a sorted index file, which is what will
actually be used to print the index.

The Texinfo command that is used to print indices is `@printindex'.
It takes the two-letter index name (*note Combining Indices::.) as an
argument without braces, and reads the corresponding sorted index
file and formats it appropriately into an index.

The two-letter index names are:

`cp'
     the concept index.

`vr'
     the variable index.

`fn'
     the function index.

`ky'
     the key index.

`pg'
     the program index.

`tp'
     the data type index.

`@printindex' does not generate a chapter heading for the index.
Consequently, you should precede the command with a suitable section
or chapter command (usually `@unnumbered') to supply the chapter
heading and put the index into the table of contents.  And before
that, you will probably put a `@node' command.  For example,

     @node Variables Index, Concept Index, Function Index, Top
     @comment    node-name,          next,       previous,  up
     @unnumbered Variable Index

     @printindex vr

     @node     Concept Index,     , Variables Index, Top
     @comment      node-name, next,        previous,  up
     @unnumbered Concept Index

     @printindex cp

     @summarycontents
     @contents
     @bye

In TeX, `@printindex' needs a sorted index file to work from.  TeX
does not know how to do sorting; this is one of the main deficiencies
of TeX.  You must invoke the program `texindex' to do so, giving it
the names of the raw index files to be sorted as arguments.  You do
not have to run `texindex' on all of them; only the ones you are
going to print.  (*Note Printing Hardcopy::, for more information.)



File: texinfo,  Node: Structuring,  Next: Quotations and Examples,  Prev: Ending a File,  Up: Top

Node and Chapter Structuring
****************************

The chapter structuring commands divide a document into a hierarchy
of chapters, sections, subsections and subsubsections.  These
commands generate large headings.

In a printed manual, the table of contents is based on the
information specified by the chapter structuring commands.

Although the chapter structuring commands used for creating a printed
document are entirely different from the node commands for
structuring an Info file, you are likely to use the two kinds of
command together since the single Texinfo file is usually designed to
be read both as an Info file and as a printed manual.  The only time
you are likely to use the chapter structuring commands without using
the node structuring commands is if you are writing a document that
will never be put into Info format, for example, a novel, a letter,
an article or a memorandum.

It is unlikely that you will ever write a Texinfo file that is only
intended as an on-line Info file and not as a printable document.
However, Texinfo is flexible enough so that you can do this if you
wish.

Although a Texinfo file can be structured in a variety of ways, it is
usually structured like a book with chapters, sections, subsections
and the like.  This structure can also be visualized as a tree (or
rather as an upside down tree) with the root at the top and each
level corresponding to chapters or sections or whatnot.  In Info
format, you reach the nodes on each level by using the the `Next' and
`Previous' pointers in the node line.  For example, you go from one
chapter to the next or previous chapter by using the the pointers to
the next and previous chapters.  In Info, you go the level above by
using an `Up' pointer and you go to the level below through a `Menu'.
In the printed manual, cross references are indicated by page and
section numbers; in the on-line file, cross references are specified
by inline menu items.

Here is a diagram that shows a Texinfo file with three chapters;
each chapter has two sections.

                                      top
                                       |
                                       |
                 ---------------------------------------------
                |                      |                      |
                |                      |                      |
            Chapter 1              Chapter 2               Chapter 3
                |                      |                      |
                |                      |                      |
           ----------             ----------              ----------
          |          |           |          |            |          |
      Sect. 1.1   Sect. 1.2   Sect. 2.1  Sect. 2.2    Sect. 3.1  Sect. 3.2


In this structure, the node for Chapter 2 looks like this:

     @node     Chapter 2,  Chapter 3, Chapter 1, top
     @comment  node-name,  next,      previous,  up

To get to Sections 2.1 and 2.2, you need a menu inside of Chapter 2
that says:

         @menu
         * Sect. 2.1::    Description of this section.
         * Sect. 2.2::
         @end menu

This menu is located inside Chapter 2, after the beginning of the
chapter, just before Section 2.1.

Note that a menu entry has three parts: the menu item name, the name
of the node and, optionally, a description of the item (in that
order).  If the menu item name and the name of the node are the same,
you can put two colons after the item name, as is shown in the
example. (If the second part is different from the first, the first
part is terminated by a colon and the second part terminated by a
tab, newline, comma or period.) (*Note Menu::.)

The node for Sect. 2.1 will look like this:

         @node     Sect. 2.1, Sect. 2.2,         ,  Chapter 2
         @comment  node-name, next,      previous,  up

This node does not have a `Previous' node.

Usually, an `@node' command and a chapter structuring command are
used in sequence, along with indexing commands.  For example, the
node for the chapter on ending a file looks like this:

     @node    Ending a File, Structuring, Beginning a File, Top
     @comment node-name,     next,        previous,         up
     @chapter Ending a Texinfo File
     @cindex  Ending a Texinfo file
     @cindex  Texinfo file ending
     @cindex  File ending

The chapter structuring commands fall into four groups that have the
characteristics of chapters, sections, subsections and subsubsections.
The groups are:

`@chapter'
`@unnumbered'
`@appendix'
     For chapters and chapter-like parts of a document.

`@section'
`@unnumberedsec'
`@appendixsec'
     For sections and section-like parts of a document.

`@subsection'
`@unnumberedsubsec'
`@appendixsubsec'
     For subsections and subsection-like parts of a document.

`@subsubsection'
`@unnumberedsubsubsec'
`@appendixsubsubsec'
     For subsubsections and subsubsection-like parts of a document.

In the sections that follow, the chapter structuring commands are
described first and then the `@node' and `@menu' commands.

* Menu:

* Chapter::
* Unnumbered and Appendix::
* Section::
* Subsection::
* Subsubsection::
* Node::
* Menu::



File: texinfo,  Node: Chapter,  Next: Unnumbered and Appendix,  Up: Structuring

@chapter
========

`@chapter' identifies a chapter in the document.  It is followed by a
single argument which is the rest of the line, as in

     @chapter Node and Chapter Structuring

In TeX, it creates a chapter in the document, specifying the chapter
title.

In the Info file, `@chapter' causes its argument to appear on a line
by itself, with a line of asterisks inserted underneath.  Thus, the
above example produces the following output:

     Node and Chapter Structuring
     ****************************



File: texinfo,  Node: Unnumbered and Appendix,  Next: Section,  Prev: Chapter,  Up: Structuring

@unnumbered, @appendix
======================

These commands are equivalent to `@chapter' for Info file output.
(*Note Chapter::.)  In a printed manual, they generate chapters that
are numbered differently in the table of contents.  `@unnumbered'
chapters appear without chapter numbers of any kind, and `@appendix'
chapters are given a letter instead of a number.



File: texinfo,  Node: Section,  Next: Subsection,  Prev: Unnumbered and Appendix,  Up: Structuring

@section
========

`@section' is like `@chapter' except that in TeX it makes a section
rather than a chapter.  (*Note Chapter::.)  Sections go within
chapters.  In the Info file, `@chapter' and `@section' differ only in
that `@section' underlines with `='.  For example,

     This is a section
     =================

@unnumberedsec, @appendixsec
============================

Use these constructs for sections within chapters made by
`@unnumbered' or `@appendix'. (*Note Section::.)



File: texinfo,  Node: Subsection,  Next: Subsubsection,  Prev: Section,  Up: Structuring

@subsection
===========

Subsections are to sections as sections are to chapters. (*Note
Section::.) They are underlined with `-'.  For example,

     This is a subsection
     --------------------

@unnumberedsubsec, @appendixsubsec
==================================

Use these constructs for subsections within sections within chapters
made by `@unnumberedsec' or `@appendixsec'.  (*Note Subsection::.)



File: texinfo,  Node: Subsubsection,  Next: Node,  Prev: Subsection,  Up: Structuring

@subsubsection And Other Subsection Commands
============================================

Subsubsections are to subsections as subsections are to sections.
(*Note Subsection::.)  They are underlined with periods.  The
equivalent commands for `@unnumberedsubsec' and `@appendixsubsec' are
`@unnumberedsubsubsec' and `@appendixsubsubsec'.  For example,

     This is a subsubsection
     .......................



File: texinfo,  Node: Node,  Next: Menu,  Prev: Subsubsection,  Up: Structuring

@node
=====

`@node' defines the beginning of a new node in the Info output file
(*note info: (info)Top.).  It is followed by four arguments,
separated by commas, that make up the rest of the line.  Since it is
often hard to remember the order in which are arguments are listed,
`texinfo-mode' provides the `C-c C-c n' command
(`texinfo-insert-@node') which automatically inserts a comment line
listing the arguments.  For example,

     @node    Texinfo Mode, Beginning a File,  Overview, Top
     @comment node-name,    next,              previous, up

defines a node named `Texinfo Mode', whose `Next' pointer is to node
`Beginning a File', whose `Previous' pointer is to node `Overview',
and whose `Up' pointer is to node `Top'.  What this means is that
Texinfo changes `@node ARGS' into the special text string necessary
to separate Info nodes and to identify the node that is starting and
say what nodes it points to.

The pointer names should be the names of nodes defined elsewhere.
For this example, nodes named `Beginning a File', `Overview' and
`Top' should be defined elsewhere in the file with other `@node'
commands.  It does not matter whether they are before or after the
node that refers to them.

Normally, a node's `Up' pointer should point at the node whose menu
mentions that node.  The node's `Next' pointer should point at the
node that follows that node and its `Previous' pointer should point
at the node that precedes it in that menu.

In TeX, `@node' is nearly ignored.  It generates no text.  Its only
function is to identify the name to use for cross-references to the
chapter or section which follows the `@node' command and which which
makes up the body of the node.  (Cross references are made with
`@xref'.  *Note Cross References::.)

`@node' should be followed immediately by a chapter-structuring
command such as `@chapter', `@section', `@subsection' or
`@subsubsection'.

The easiest way to write a node is to use the Texinfo mode keyboard
command `C-c C-c n' to insert `@node' and a comment line listing the
names of each of the pointers in their proper order.  This way you
won't lose track of which arguments are for which pointers.  The
template is especially useful if you are not familiar with Texinfo.
It is important to pick a suitable node name.  Generally, these begin
with an uppercase letter as if the node name were a heading for a
chapter or section.  Do not use any of the Texinfo @-commands in the
name; these commands confuse Info.  The node name should be
informative.  Unfortunately, long names will not fit onto the line,
which can be awkward.  Sometimes it is better to use long but
informative names rather than short ones.

Some people insert the names of the `Next', `Previous' and `Up'
pointers at the same time they insert the node's own name.  This is
because it is easier to keep track of the node structure as you
create a document than it is to sort it out after you have dozens of
nodes.  Others wait to insert the `Next', `Previous' and `Up'
pointers until they have a nearly final version of the document.
This is because they expect to change the organization of the
document while they write it and insert or delete sections and move
them around.  The command `texinfo-show-structure' can be used to
find the `Next', `Previous' and `Up' pointers of a node.  (See *Note
Using texinfo-show-structure::.)

However you do it, it is best to name the node whenever you write the
section so you can easily make cross references to the section.  A
large number of cross references are an especially important feature
of a good Info file.

After you have inserted the node-line, you should immediately write
an @-command for the chapter or section and insert its name.  Next,
(and this is important!), put in several index entries.  Usually, you
will find at least two and often as many as four or five ways of
referring to the node in the index.  Use them all.  This will make it
much easier for people to find the node.

The top node of the file, named `Top', should have as its parent the
name of a node in another file, where there is a menu that leads to
this file.  Specify the file name in parentheses.  If the file is to
be installed directly in the Info directory file, use `(dir)' as the
parent of the top node; this is short for `(dir)top', the node `top'
in the file `dir', which is the main menu of Info.  For example,

     @node    Top,       Overview, (dir),    (dir)
     @comment node-name, next,     previous, up

For more information about installing an Info file in the `info'
directory, *note Installing an Info File::.



File: texinfo,  Node: Menu,  Prev: Node,  Up: Structuring

@menu
=====

Info file nodes can contain "menus" which point to other nodes.  You
must type the menus in by hand, and surround them with lines
containing `@menu' and `@end menu'.  In Info, the `@menu' line
changes into `* Menu:', which indicates the beginning of a menu to
the Info program.  Otherwise, the contents are unchanged by Texinfo,
except for the processing of any other @-commands within.  The entire
menu construct has no effect in the printed manual and will not
appear there.

By convention, a menu is put at the end of a node.  This way, it is
easy for someone using Info to find the menu, using the `M->'
(`end-of-buffer') command.

In a menu, every line that begins with a `*' lists a single topic.  A
line that does not start with a `*' will also appear in the menu and
can be used as a comment.

A menu item has three parts:

  1. The menu item name.

  2. The name of the node.

  3. A description of the item.

Only the first part is required.  This part is the name of the
topic--the name of the menu item that the user must give to the `m'
command to select this topic when using Info.  The first part comes
right after the asterisk and a space, and is followed by a colon,
spaces and tabs, and then the name of the node which discusses that
topic.  The name of the node is terminated by a tab, comma, newline
or period.  If the node name and topic name are the same, rather than
give the name twice, put two colons after the name instead.  For
example, `* Name::'.  (You should do this whenever possible, since it
reduces visual clutter in the menu).

If the second part is present, it may be terminated with a tab,
comma, or newline; or with a period.

For example,

     @menu
     A Section on Foo and Switches
     * Foo::           The node named Foo tells you how to go fooing.
     * Sw: Switches.   Type @code{m Sw} to see node @code{Switches}
                       which describes the switches available here.
     @end menu

produces

     * menu:

     A Section on Foo and Switches
     * Foo::         The node named foo tells you how to go fooing.
     * Sw: Switches. Type `m Sw' to see node `Switches'
                     which describes the switches available here.

 In this example, the menu has two items.  `Foo' is both a menu item
name and the name of the node referred to by that item.  `Sw' is the
other menu item name, and it refers to the node named `Switches'.
Since no file name is specified with `Foo' or `Switches', they must
be the names of other nodes in the same Info file.

Nodes in other Info files can be referred to by putting the file name
in parentheses at the beginning of the node name. For example,

     @menu
     * Outlining: (emacs) Outline Mode.  The major mode for editing outlines.
     * Rebinding: (emacs) Rebinding.     How to redefine the meaning of a key.
     @end menu

When this is done, the item has to have at least two parts: the first
part is the menu item name and the second part is the name of the node.



File: texinfo,  Node: Quotations and Examples,  Next: Lists and Tables,  Prev: Structuring,  Up: Top

Making Quotations and Examples
******************************

Quotations and examples are blocks of text, consisting of one or more
whole paragraphs that are set off from the bulk of the text and
treated differently.  They are usually indented.

In Texinfo, an insertion is always begun by writing an @-command on a
line by itself, and ended by writing an `@end' command that is also
on a line by itself.  For instance, an "example" is a kind of
insertion that is begun with `@example' and ended with `@end example'.

There are three commands for quotations and examples:

`@quotation'
     Used to indicated text that is quoted.

`@example'
     Used to illustrate code, commands and the like in a fixed width
     font without filling.

`@display'
     Used for illustrative text.

* Menu:

* Quotation::
* Example::
* Display::



File: texinfo,  Node: Quotation,  Next: Example,  Up: Quotations and Examples

@quotation
==========

`@quotation' is used to indicate text that is excerpted from another
(real or hypothetical) printed work.  The inside of a quotation is
processed normally except that

  1. The margins are narrower.

  2. Paragraphs are not indented.

  3. Interline spacing and interparagraph spacing are reduced.

Thus, the input

     @quotation
     This is
     a foo.
     @end quotation

produces in the printed manual

          This is a foo.

and in the Info file

          This is
          a foo.



File: texinfo,  Node: Example,  Next: Display,  Prev: Quotation,  Up: Quotations and Examples

@example
========

`@example' is used to indicate an example that is not part of the
running text.  In the printed manual, this is done by switching to a
fixed width font, turning off filling, and making extra spaces and
blank lines significant.  In the Info file, an analogous result is
obtained by indenting each line with five extra spaces.

`@example' should appear on a line by itself; this line will
disappear from the output.  Mark the end of the example with a line
containing `@end example', which will likewise disappear.  For example:

     @example
     mv foo bar
     @end example

produces

     mv foo bar

Since the lines containing `@example' and `@end example' will
disappear, you will want to put a blank line before the `@example'
and another blank line after the `@end example'.  (Remember that
blank lines between the beginning `@example' and the ending `@end
example' will appear in the output.)

Don't use tabs in lines of an example!  TeX has trouble with tabs:
it treats them like single spaces, and that is not what they look like.



File: texinfo,  Node: Display,  Prev: Example,  Up: Quotations and Examples

@display
========

`@display' is just like `@example' except that, in the printed
manual, `@display' does not select the fixed-width font.  In fact, it
does not specify the font at all, so that the text appears in the
same font it would have appeared in without the `@display'.



File: texinfo,  Node: Lists and Tables,  Next: Cross References,  Prev: Quotations and Examples,  Up: Top

Making Lists and Tables
***********************

Texinfo has several ways of making lists and two-column tables.
Lists can be bulleted or numbered while two-column tables can
highlight the items in the first column.

For example, this is an enumerated list:

  1. This is a numbered item.

  2. This is the second item in this list.

  3. This is the third item on this list.

Texinfo will automatically indent the text in lists or tables and
number an enumerated list.  This last feature is useful if you are
reordering the list, since you do not have to renumber it yourself.

Lists or tables are always begun by an @-command on a line by itself
and ended with an `@end' command on a line by itself.  For example,
an enumerated list begins with the command `@enumerate' and ends with
the command `@end enumerate'; and an itemized list begins with the
command `@itemize' and ends with the command `@end itemize'.

The elements of a list are begun with the `@item' command.

Here is an itemized list of the different kinds of table and lists:

   * Itemized lists with or without bullets.

   * Numbered lists.

   * two-column tables with highlighting.

* Menu:

* Itemize::
* Enumerate::
* Table::



File: texinfo,  Node: Itemize,  Next: Enumerate,  Up: Lists and Tables

@itemize
========

`@itemize' is used to produce sequences of indented paragraphs, with
a mark inside the left margin at the beginning of each paragraph.
The rest of the line that starts with `@itemize' should contain the
character or Texinfo commands to generate such a mark.  Usually, it
is the @-command `@bullet'.  Whatever mark you choose, ultimately, it
should result in a single character in the Texinfo file, or the
indentation will come out wrong.  When you write the command, omit
the `{}' after the command if you use just one command and nothing
else.

The text of the indented paragraphs themselves come after the
`@itemize', up to another line that says `@end itemize'.

Before each paragraph for which a mark in the margin is desired,
place a line that says just `@item'.  Don't put any other text on
this line.

Info indents the lines in an itemized list by five columns, but it
does not fill them.  This can produce lines in the Info file that are
too wide.  You can either write shorter lines in the Texinfo file by
setting the fill column to five columns less than it is normally, or
else you can tell Info to refill the paragraphs by adding the
@-command `@refill' to the end of the paragraph. (*Note Refill::, for
more information about the use of the `@refill' command.)

Usually, you should put a blank line before an `@item'.  This puts a
blank like in the Info file.  Except when the entries are very brief,
a blank line looks better.

Here is an example of the use of `@itemize', followed by the output
it produces.  Note that `@bullet' produces a `*' in Texinfo and a
round dot in TeX.

     @itemize @bullet
     @item
     Some text for foo.

     @item
     Some text
     for bar.
     @end itemize

produces

        * Some text for foo.

        * Some text for bar.



File: texinfo,  Node: Enumerate,  Next: Table,  Prev: Itemize,  Up: Lists and Tables

@enumerate
==========

`@enumerate' is like `@itemize' except that the marks in the left
margin contain successive integers starting with 1.  (*Note
Itemize::.) Do not put any argument on the same line as `@enumerate'.

     @enumerate
     @item
     Some text for foo.
     @item
     Some text
     for bar.
     @end enumerate

produces

       1. Some text for foo.

       2. Some text for bar.

If you want, you can put a blank line between the entries in the list.
This often makes it easier to read the Info file.  For example,

     @enumerate
     @item
     This is the first item.

     @item
     This is the second item.
     @end enumerate

Info indents the lines of the enumerated list by five columns, but it
does not fill them.  As a result, the lines in the Info file may be
too wide.  To prevent this, you can either write shorter lines in the
Texinfo file file by setting the fill column to five columns less
than it is normally, or else you can tell Info to refill the
paragraphs by adding the @-command `@refill' to the end of the
paragraph.  (*Note Refill::, for more information about the use of
the `@refill' command.)



File: texinfo,  Node: Table,  Prev: Enumerate,  Up: Lists and Tables

@table
======

`@table' is similar to `@itemize', but allows you to specify a name
or heading line for each item.  (*Note Itemize::.)  The command is
used to produce two-column tables, and is especially useful for
glossaries and explanatory exhibits.

You must follow each use of `@item' inside of `@table' with text to
serve as the heading line for that item.  This text is put on the
same line as the `@item' command.  Each heading line is put into the
first column of the table and the supporting text, which you put on
the line following the line beginning with `@item', goes into the
second column.

Also, `@table' itself must be followed by an argument that is a
Texinfo command such as `@code', `@var', `@kbd' or `@asis'.  Although
these commands are usually followed by arguments in braces, in this
case you use the command name without an argument.  (`@item' supplies
the argument.)  This command will be applied to the text that goes
into the first column of each item and determines how it will be
highlighted.  For example, `@samp' will cause the text in the first
column to be highlighted as if it were acted on by an `@samp' command.

`@asis' is a command that does nothing; in that case, each item will
come out without highlighting, unless that particular piece of text
contains @-commands for highlighting.

(Various other command names might work with `@table'.  However, only
commands that normally take arguments in braces may be used.)

Usually, you should put a blank line before an `@item'.  This puts a
blank like in the Info file.  Except when the entries are very brief,
a blank line looks better.

The following table, for example, highlights the text in the first
column as if each item were acted on by an `@samp' command:

     @table @samp
     @item foo
     This is the text for
     @samp{foo}.

     @item bar
     Text for @samp{bar}.
     @end table

produces

    `foo'
          This is the text for `foo'.

    `bar'
          Text for `bar'.

Info indents the lines of text in the second column, but does not
fill them.  As a result, the lines in the Info file may be too wide.
To prevent this, cause Info to refill the paragraphs after processing
by adding the @-command `@refill' to the end of the paragraph. (*Note
Refill::, for more information about the use of the `@refill' command.)

If you want to list two or more named items with a single block of
text, use the `@itemx' command.

* Menu:

* Itemx::



File: texinfo,  Node: Itemx,  Prev: Table,  Up: Table

@itemx
------

`@itemx' is used inside a `@table' when you have two or more named
items for the same block of text.  Use `@itemx' for all but the first
of the items.  It works exactly like `@item' except that it does not
generate extra vertical space above the item text.  For example,

     @table @code
     @item upcase
     @itemx downcase
     These two functions accept a character or a string as argument,
     and return the corresponding upper case (lower case) character
     or string. @refill
     @end table

produces

    `upcase'
    `downcase'
          These two functions accept a character or a string as
          argument, and return the corresponding upper case (lower
          case) character or string.

A more complicated example of the use of `@itemx' comes from the
chapter on structuring commands.  Here is how the list showing how
the chapter structuring commands fall into four groups was constructed.
(*Note Chapter Structuring Commands: Structuring.)

     @table @code
     @item  @@chapter
     @itemx @@unnumbered
     @itemx @@appendix
     For chapters and chapter-like parts of a document.

     @item  @@section
     @itemx @@unnumberedsec
     @itemx @@appendixsec
     For sections and section-like parts of a document.

     @item  @@subsection
     @itemx @@unnumberedsubsec
     @itemx @@appendixsubsec
     For subsections and subsection-like parts of a document.

     @item  @@subsubsection
     @itemx @@unnumberedsubsubsec
     @itemx @@appendixsubsubsec
     For subsubsections and similar parts of a document.
     @end table

and this is what the resulting table looks like:

`@chapter'
`@unnumbered'
`@appendix'
     For chapters and chapter-like parts of a document.

`@section'
`@unnumberedsec'
`@appendixsec'
     For sections and section-like parts of a document.

`@subsection'
`@unnumberedsubsec'
`@appendixsubsec'
     For subsections and subsection-like parts of a document.

`@subsubsection'
`@unnumberedsubsubsec'
`@appendixsubsubsec'
     For subsubsections and similar parts of a document.

Also, either column of a table can be empty.



File: texinfo,  Node: Cross References,  Next: Formatting Paragraphs,  Prev: Lists and Tables,  Up: Top

Making Cross References
***********************

Cross references are used to refer the reader to other parts of the
same or different Texinfo files.  In Texinfo, "nodes" are the points
to which cross-references can refer.

In general, a document should be designed so that it can be read
sequentially.  People soon tire of flipping back and forth to find
information that should be presented to them as they need it.
However, there will be information (often too detailed for whatever
the current context may be) that is related to whatever is presented
and to which reference should be made.  More important, in an on-line
help system or in a reference manual, readers do *not* read
everything in sequence from beginning to end.  Instead, they look up
what they need.  For this reason, such creations should contain many
cross references to help the reader find other information that he or
she may not have read.

Although nodes are not a fundamental concept in a printed manual,
they still serve to define a cross-reference point and the variants
of `@xref' still serve to make references.  Thus, if you are writing
a manual that will only be printed, and will not be used on-line, you
continue to use the `@node' command for when you make cross references.

There are several kinds of cross reference command.

`@xref'
     Used to start a sentence in the printed manual saying, `See ...'
      or an entry in the Info file saying `*note ...'.

`@pxref'
     Used to make a reference that starts with a lowercase `see'
      and is usually contained within parentheses.

`@inforef'
     Used to make a reference to an Info file for which there is no
     printed manual.

* Menu:

* Xref::
* Pxref::
* Inforef::



File: texinfo,  Node: Xref,  Next: Pxref,  Prev: Cross References,  Up: Cross References

@xref
=====

`@xref' generates a cross-reference.  In Texinfo, it turns into an
Info cross-reference which the Info `f' command can use to go
directly to another node.  In TeX, it turns into a sentence of the form

     See section SECTION [TOPIC], page PAGE

but does not generate a period to end it.

`@xref' must refer to an Info node created by `@node', by the node's
name.

`@xref' is followed by an argument inside braces; but actually the
text inside the braces is treated as several arguments, separated by
commas.  Whitespace after these commas is ignored.  A period or comma
*must* follow the closing brace of an `@xref'.  It is required to
terminate the cross reference.  This period or comma will appear in
the output, both in the Info file and in the printed manual.

The simplest form of `@xref' takes one argument, the name of another
node in the same Info file.  Here we show the input text, followed by
a blank line and then the output text for Info files and the output
text for printed manuals.

     @xref{node-name}, for more info.

     *note node-name::, for more info.

      See section NNN [node-name], page PPP, for more info.

With two arguments, the second one is used as the name of the Info
cross-reference, while the first argument is still the node that the
cross-reference points to:

     @xref{node-name, name-for-note}, for more info.

     *note name-for-note: node-name, for more info.

      See section NNN [node-name], page PPP, for more info.

A third argument replaces the node name when it actually appears in
the TeX output.  It should state the topic discussed by the section
being referenced.  Often, you will want to use initial uppercase
letters so it will be easier to read when the reference is printed.
Use a third argument when the node name is unsuitable because of
syntax, grammar or diction.

     @xref{node-name, name-for-note, Topic Description}, for more info.

     *note name-for-note: node-name, for more info.

      See section NNN [Topic Description], page PPP, for more info.

If a third argument is given and the second one is empty, then the
third argument serves both purposes:

     @xref{node-name, , Topic Description}, for more info.

     *note Topic Description: node-name, for more info.

      See section NNN [Topic Description], page PPP, for more info.

A fourth argument specifies the name of the Info file in which the
referenced node is located, assuming it is not the one in which the
reference appears.  `@xref' with only four arguments is used when the
reference is not within one Info file, but is within a single printed
manual--when multiple Texinfo files are incorporated into the same
TeX run but make separate Info files.  (This is seldom the case and
usually you will use five arguments if you are making a reference
that is outside the current Info file.)

     @xref{node-name, name-for-note, Topic, info-file-name},
     for more info.

     *note name-for-note: (info-file-name) node-name, for more info.

      See section NNN [Topic], page PPP, for more info.

A fifth argument is used when you are making a reference to another
Info file which is also part of another printed manual.  Write the
title of the manual in this slot.  Since a different manual is made
during a different TeX run, the printed reference will not have a
page number.

Whenever you refer to another manual, use this version of `@xref'
with five arguments.

     @xref{node-name, name-for-note, Topic, info-file-name, A Printed Manual},
     for more info.

     *note name-for-note: (info-file-name) node-name, for more info.

      See section Topic of A Printed Manual, for more info.

The name of the printed manual will be typeset in italics.

Often, you will leave out the second argument when you use the long
version of `@xref'.  In this case, the third argument, the topic
description, will replace the node name:

     @xref{node-name, , Topic Description, info-file-name, A Printed Manual},
     for more info.

     *note Topic Description: (info-file-name) node-name, for more info.

      See section Topic Description of A Printed Manual, for more info.



File: texinfo,  Node: Pxref,  Next: Inforef,  Prev: Xref,  Up: Cross References

@pxref
======

`@pxref' is nearly the same as `@xref'; it differs in only two ways:

  1. The output starts with lower case `see' rather than `See'.

  2. A period is generated automatically in the Info file output to
     end the Info cross-reference, but no period is generated for the
     printed manual.

The purpose of `@pxref' is to be used inside parentheses as part of
another sentence.  In the printed manual, no period is needed after
the cross reference text itself (within the parentheses), but a
period is needed after the cross reference text in the Info file
because only thus can Info recognize the end of the cross-reference.
`@pxref' spares you the need to use complicated methods to put a
period into one form of the output and not the other.

`@pxref' can be used with up to five arguments just like `@xref'.
(*Note Xref::.)



File: texinfo,  Node: Inforef,  Prev: Pxref,  Up: Cross References

@inforef
========

`@inforef' is used for cross-references to Info files for which there
are no printed manuals.  Even in a printed manual, `@inforef'
generates a reference directing the user to look in an Info file.
`@inforef' takes exactly three arguments.  The syntax is
`@inforef{NODE, NAME, FILE}'.

     @inforef{node-name, name-for-note, info-file-name}, for more information.

     *note name-for-note: (info-file-name) node-name, for more information.

      See Info file `info-file-name', node `node-name', for more
     information.



File: texinfo,  Node: Formatting Paragraphs,  Next: Marking Text,  Prev: Cross References,  Up: Top

Formatting Paragraphs
*********************

Usually, a Texinfo file will be processed both by TeX and by the `M-x
texinfo-format-buffer' command.  Consequently, you must make sure
that text will come out looking right both in the printed manual and
in the on-line help.

For example, unless told otherwise, `M-x texinfo-format-buffer' will
not refill a paragraph after processing it although TeX will.  This
means that a paragraph with numerous or large @-commands may not look
properly filled after processing by Info.  The @-commands are removed
from the text but the lines are not refilled so some are much shorter
than they were.  To cause the `M-x texinfo-format-buffer' command to
refill such a paragraph, put `@refill' at the end of the paragraph.

TeX may also format a document improperly.  For example, page breaks
may occur in the "wrong place"; to control this, text can be held
together by a group command that keeps the text within the group from
being split across two pages.

* Menu:

* Refilling & Noindent::      Refilling paragraphs & preventing indentation
* Breaks Blank-Lines Groups::  Line and paragraph breaks, blank lines, grouping



File: texinfo,  Node: Refilling & Noindent,  Next: Breaks Blank-Lines Groups,  Prev: Formatting Paragraphs,  Up: Formatting Paragraphs

Refilling Paragraphs and Preventing Indentation
===============================================

The `@refill' and `@noindent' commands are used just after or just
before paragraphs which, after processing by either Info or TeX,
might look bad.  The `@refill' command refills a paragraph in the
Info file after all the other processing has been done.  In the
printed manual, the `@noindent' command prevents a piece of text that
is a continuation of the preceding paragraph from being indented as
if it were a new paragraph.

* Menu:

* Refill::    Refilling an info paragraph after other processing.
* Noindent::    Preventing paragraph indentation in continuation text.



File: texinfo,  Node: Refill,  Next: Noindent,  Prev: Refilling & Noindent,  Up: Refilling & Noindent

@refill
-------

If a paragraph contains sizable @-constructs, it may look badly
filled after `texinfo-format-buffer' is through with it.

Put `@refill' at the end of the paragraph to tell
`texinfo-format-buffer' to refill the paragraph after finishing all
other processing on it.  `@refill' has no effect on TeX, which always
fills everything that ought to be filled.  For example,

     To use @code{foo}, pass @samp{xx%$} and @var{flag} and type @kbd{x}
     after running @code{make-foo}.@refill

produces (in the Info file)

     To use `foo', pass `xx%$' and FLAG and type `x' after running `make-foo'.

 whereas without the `@refill' it would produce

     To use `foo', pass `xx%$' and FLAG and type `x'
     after running `make-foo'.

 with the line broken at the same place as in the Texinfo input file.

Do not put a space before `@refill'; otherwise the command might be
put at the beginning of the line when you refill the paragraph in the
Texinfo file with `M-q' (`fill-paragraph').  If this were to happen,
the `@refill' command might fail to work



File: texinfo,  Node: Noindent,  Prev: Refill,  Up: Refilling & Noindent

@noindent
---------

If you have text following an `@example' or other similar "special
paragraph" that reads as a continuation of the text before the
`@example', it is good to prevent this text from being indented as a
new paragraph.  To accomplish this, put `@noindent' on a line by
itself before the start of the text that should not be indented. For
example,

     @example
     This is an example
     @end example

     @noindent
     This line will not be indented.

 produces

     This is an example

This line will not be indented.

To adjust the number of blank lines properly in the Info file output,
remember that the line containing `@noindent' does not generate a
blank line, and neither does the `@end example' line.

In the Texinfo source file for this documentation, each of the lines
that says `produces' is preceded by a line containing `@noindent'.